home *** CD-ROM | disk | FTP | other *** search
/ Aminet 52 / Aminet 52 (2002)(GTI - Schatztruhe)[!][Dec 2002].iso / Aminet / comm / irc / epic4.lha / doc / colors < prev    next >
Text File  |  2002-09-18  |  11KB  |  189 lines
  1. (Not everything in this file is 100% accurate...)
  2.  
  3. This version of epic contains J. Kean Johnston's color stripping
  4. code.  This code is an attempt at making color support more UNIX friendly
  5. in IRC clients.  The color parsing code has been designed to fit in with
  6. my term.c replacement as well.
  7.  
  8. The aim of this code is to strip all incoming messages of non-portable
  9. color codes, and to convert those color codes to the codes specific to the
  10. terminal type of the user, if such codes exist. It also extends mIRC and
  11. PIRCH's Ctrl-C color codes to allow for an easier set of supported colors.
  12. Please encourage the authors of those programs to adhere to this set, so
  13. that we can have uniformity amongst the competing clients out there.
  14.  
  15. Since ANSI escape codes have been around for so long, and are so widely
  16. used in so many environments, this code uses the ANSI escape codes as its
  17. base.  That is, it can understand ANSI escape sequences in incoming
  18. strings, and map those sequences down to terminal-specific escape
  19. sequences.  The color numbers supported in Ctrl-C type strings also match
  20. the ANSI color set.  For your reference, here are the extended Ctrl-C
  21. sequences this code recognises, and the ANSI escape sequences recognised.
  22. These map down to a specific color on the display:
  23.  
  24. +---------------------------------------------------------------------+
  25. |                   Extended Ctrl-C color numbers                     |
  26. +-----------------+-----------------------+---------------------------+
  27. | Ctrl-C Number   |  ANSI Escape Sequence | Color                     |
  28. +-----------------+-----------------------+---------------------------+
  29. |       30        | ESC [ 0; 30 m         | Black foreground          |
  30. |       31        | ESC [ 0; 31 m         | Red foreground            |
  31. |       32        | ESC [ 0; 32 m         | Green foreground          |
  32. |       33        | ESC [ 0; 33 m         | Brown foreground          |
  33. |       34        | ESC [ 0; 34 m         | Blue foreground           |
  34. |       35        | ESC [ 0; 35 m         | Magenta foreground        |
  35. |       36        | ESC [ 0; 36 m         | Cyan foreground           |
  36. |       37        | ESC [ 0; 37 m         | White foreground          |
  37. |       40        | ESC [ 40 m            | Black background          |
  38. |       41        | ESC [ 41 m            | Red background            |
  39. |       42        | ESC [ 42 m            | Green background          |
  40. |       43        | ESC [ 43 m            | Brown background          |
  41. |       44        | ESC [ 44 m            | Blue background           |
  42. |       45        | ESC [ 45 m            | Magenta background        |
  43. |       46        | ESC [ 46 m            | Cyan background           |
  44. |       47        | ESC [ 47 m            | White background          |
  45. |       50        | ESC [ 1; 30 m         | Grey foreground           |
  46. |       51        | ESC [ 1; 31 m         | Bright red foreground     |
  47. |       52        | ESC [ 1; 32 m         | Bright green foreground   |
  48. |       53        | ESC [ 1; 33 m         | Yellow foreground         |
  49. |       54        | ESC [ 1; 34 m         | Bright blue foreground    |
  50. |       55        | ESC [ 1; 35 m         | Bright magenta foreground |
  51. |       56        | ESC [ 1; 36 m         | Bright cyan foreground    |
  52. |       57        | ESC [ 1; 37 m         | Bright white foreground   |
  53. +-----------------+-----------------------+---------------------------+
  54.  
  55. In order to support existing mIRC color codes, the following map is applied
  56. to Ctrl-C colors with the given values.  Note that each color can have a
  57. slightly different value when interpreted as a foreground or a background
  58. color. This is the problem with the color set the mIRC author chose. Unless
  59. the user is on a graphics device with a large color pallete, the mappings
  60. are inaccurate.
  61.  
  62. +-------------------------------------------------------------------------+
  63. |                     mIRC Ctrl-C color mappings                          |
  64. +----------+-----------------+-----------------+--------------------------+
  65. | Ctrl-C # | Foreground ANSI | Background ANSI | Fore / back Color        |
  66. +----------+-----------------+-----------------+--------------------------+
  67. |    0     | ESC [ 1; 37 m   | ESC [ 47 m      | Bright white / White     |
  68. |    1     | ESC [ 0; 30 m   | ESC [ 40 m      | Black / Black            |
  69. |    2     | ESC [ 0; 34 m   | ESC [ 44 m      | Blue / Blue              |
  70. |    3     | ESC [ 0; 32 m   | ESC [ 42 m      | Green / Green            |
  71. |    4     | ESC [ 0; 31 m   | ESC [ 41 m      | Red / Red                |
  72. |    5     | ESC [ 0; 33 m   | ESC [ 43 m      | Brown / Brown            |
  73. |    6     | ESC [ 0; 35 m   | ESC [ 45 m      | Magenta / Magenta        |
  74. |    7     | ESC [ 1; 31 m   | ESC [ 41 m      | Bright red / Red         |
  75. |    8     | ESC [ 1; 33 m   | ESC [ 43 m      | Yellow / brown           |
  76. |    9     | ESC [ 1; 32 m   | ESC [ 42 m      | Bright green / Green     |
  77. |    10    | ESC [ 0; 36 m   | ESC [ 46 m      | Cyan / Cyan              |
  78. |    11    | ESC [ 1; 36 m   | ESC [ 46 m      | Bright Cyan  Cyan        |
  79. |    12    | ESC [ 1; 34 m   | ESC [ 44 m      | Bright blue / Blue       |
  80. |    13    | ESC [ 1; 35 m   | ESC [ 45 m      | Bright Magenta / Magenta |
  81. |    14    | ESC [ 1; 30 m   | ESC [ 40 m      | Grey / Black             |
  82. |    15    | ESC [ 0; 37 m   | ESC [ 40 m      | Grey / White             |
  83. +----------+-----------------+-----------------+--------------------------+
  84.  
  85. By special dispensation, there is also a function which can be used for
  86. preparing strings with color in scripts or in settable variables.  There is
  87. a function which will replace these special formatting variables with the
  88. appropriate Ctrl-C colors, if colorization is turned on.  The table below
  89. lists the escape sequences recognised, and what they are replaced with.
  90.  
  91. +-------------------------------------------------------------+
  92. |              Embedded color escape sequences                |
  93. +---------+-----------------------+---------------------------+
  94. | % char  |  ANSI Escape Sequence | Color                     |
  95. +---------+-----------------------+---------------------------+
  96. |   %k    | ESC [ 0; 30 m         | Black foreground          |
  97. |   %K    | ESC [ 1; 30 m         | Grey foreground           |
  98. |   %r    | ESC [ 0; 31 m         | Red foreground            |
  99. |   %R    | ESC [ 1; 31 m         | Bright red foreground     |
  100. |   %g    | ESC [ 0; 32 m         | Green foreground          |
  101. |   %G    | ESC [ 1; 32 m         | Bright green foreground   |
  102. |   %y    | ESC [ 0; 33 m         | Brown foreground          |
  103. |   %Y    | ESC [ 1; 33 m         | Yellow foreground         |
  104. |   %b    | ESC [ 0; 34 m         | Blue foreground           |
  105. |   %B    | ESC [ 1; 34 m         | Bright blue foreground    |
  106. | %m / %p | ESC [ 0; 35 m         | Magenta foreground        |
  107. | %M / %P | ESC [ 1; 35 m         | Bright magenta foreground |
  108. |   %c    | ESC [ 0; 36 m         | Cyan foreground           |
  109. |   %C    | ESC [ 1; 36 m         | Bright cyan foreground    |
  110. |   %w    | ESC [ 0; 37 m         | White foreground          |
  111. |   %W    | ESC [ 1; 37 m         | Bright white foreground   |
  112. |   %F    | ESC [ 5 m             | Turn blinking on          |
  113. |   %f    | ESC [ 6 m             | Turn blinking off         |
  114. |   %n    | Variable              | All colors turned off     |
  115. |   %N    | Nothing               | Dont clear colors at EOS  |
  116. |   %%    | %                     | A litteral % character    |
  117. +---------+-----------------------+---------------------------+
  118.  
  119. What colors.c does
  120. ------------------
  121. The colorization module provides several utility functions designed to ease
  122. the display of strings on the local client.  These functions should be used
  123. to prepare the final output string to the clients screen.  Firstly, there
  124. is a "stripper" function.  This will remove all color formatting characters
  125. and escape sequences from the specified string, and return it.  This
  126. fucntion can optionally repove any graphics characters from the string as
  127. well (upper PC ASCII characters, and all lower ASCII characters).  NOTE:
  128. this will remove characters such as ^B, ^V and ^_, the characters used to
  129. turn on bold, inverse and underline in a string.  This function is rather
  130. brutal in its removal of string characters.
  131.  
  132. Another function provided will take the given input string and convert any
  133. embedded ANSI or Ctrl-C color codes to the color codes supported by the
  134. users terminal.  It will also insert the escape sequences for turning on
  135. and off the bold, inverse and underline modes when ^B, ^V and ^_ are
  136. encountered in the string.  This function can be used to prepare a "final"
  137. string for display.  The function will optionally convert any upper and
  138. lower ASCII characters to their graphics equivalents if your terminal
  139. supports them, or will inverse the characters or strip off the high bit if
  140. your terminal does not support the display of special PC characters.
  141.  
  142. A third function is basically an extension of the second, except it takes
  143. "fill prefix" and width arguments, and will prepare a set of strings ready
  144. to display to the client, including wrapping and insertion of the fill
  145. string.  This correctly calculates the string lengths so as to exclude
  146. special characters when calculating when to wrap the string.
  147.  
  148. User control over the colorization process
  149. ------------------------------------------
  150. There are a few variables the user can set to control the colorization and
  151. stripping process.  They are:
  152.  
  153. /set CONTROL_C_COLOR
  154.     OFF - Dont allow any color codes at all
  155.     ON  - Allow all coolors codes
  156.  
  157. /set DISPLAY_ANSI
  158.     OFF - Do not do any ansi-code translation, Mangle escapes
  159.     ON  - Translate all 'safe' codes to their logical equivalents.
  160.           Strip out all other codes.
  161.  
  162. DISPLAY_PC_CHARACTERS
  163.   Legal values: 0, 1, 2, 3, 4, 5
  164.   0  - Strip all upper ASCII and lower ASCII strings except for ^B, ^V,
  165.        ^_ and ^F.
  166.   1  - If the terminal has dispc/S1 capability, use it.
  167.        Otherwise, use the "traditional" 7-bit interverted translation.
  168.        (eg: (x | 0x40 & 0x7f) (you have to see it to understand)) (default)
  169.   2  - Same as #1, except the translation is done in a more 'sane' way and
  170.        attempts to render in a way more friendly to scripts that are using
  171.        8 bit characters to "draw".  Translated characters are inverted so
  172.        that you know they were translated.
  173.   3  - Same as #2, except translated characters are not inverted.
  174.   4  - Always display characters without translation.
  175.   5  - Always display characters with "sane" translation.
  176.  
  177. Things still to do
  178. ------------------
  179. a) Preparing long display strings for display optimization
  180. b) Making the input stuff color / ROM CHAR friendly  (done!)
  181. c) Make the graphics character translation map configurable
  182. d) Some minor cleanups which reduce function overhead
  183. e) Calculate more values at the start of the display calc loop for speed
  184. f) Much more testing
  185. g) Handle things where terminal cant turn off auto-margins (I think this
  186.    is already handled correctly). (durn bogus terminals!)
  187. h) Make more code use the accululator to speed up displays
  188. i) Actually write the accumulator :-)
  189.